Implement initial PyAutoBrain Bug Agent#20
Merged
Merged
Conversation
Add agents/conductors/bug/ — a new PyAutoBrain conductor framed as the organism's immune system: recognise a bug / regression / failing test / PyAutoHeart finding, tell it from benign self, classify it (severity/scope/type/confidence), decide where the fix belongs (source-first; never degrade a user-facing workspace script, the autoimmune failure mode), and emit a BugDecision the start_dev -> ship_* workflow consumes. It reasons; it never edits source. - _bug.py reuses the Feature Agent core (parse_prompt / estimate_difficulty / memory_context / in-flight down-ranking) and adds classify / reproduction / fix_locus / health_mode; stdlib-only, offline, never writes. - bug.sh entrypoint; health mode reads the live vitals verdict AND scans filed PyAutoHeart issues (gh), routing real defects to bug/health_fixes/. - Consults the vitals faculty, never Heart directly; conductor-only with a documented seam for a future read-only diagnosis faculty. - Promote /bug from a work-type entry to a real conductor across bin/pyauto-brain, skills/bug/bug.md, skills/COMMANDS.md, README.md, AGENTS.md. Refs #18 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR introduces an initial Bug Agent as a new PyAutoBrain conductor (agents/conductors/bug/) and promotes /bug from a work-type routing entry to a first-class command that emits a structured BugDecision for the existing start_dev → ship_* workflow.
Changes:
- Add the Bug Agent conductor (docs, taxonomy, bash entrypoint, and deterministic Python analysis core).
- Register
pyauto-brain bugand promote/bugacross the command surface docs. - Reuse Feature Agent deterministic helpers via import to avoid forking shared logic.
Reviewed changes
Copilot reviewed 8 out of 9 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/COMMANDS.md | Promotes /bug into the real-conductors table and removes it from work-type entries. |
| skills/bug/bug.md | Updates /bug user-facing instructions to call the Bug Agent conductor. |
| README.md | Documents the new Bug Agent conductor in the repo overview and command taxonomy. |
| bin/pyauto-brain | Registers the bug agent script/description and includes it in conductor ordering. |
| agents/conductors/bug/bug.sh | Adds the Bug Agent deterministic entrypoint (modes, flags, vitals + Heart-issues scan). |
| agents/conductors/bug/BUG_TAXONOMY.md | Defines bug classification/fix-locus taxonomy and health-input semantics for the agent. |
| agents/conductors/bug/AGENTS.md | Adds the Bug Agent conductor documentation and BugDecision schema narrative. |
| agents/conductors/bug/_bug.py | Implements prompt discovery/selection, bug classification, fix locus/strategy, and decision emission. |
| AGENTS.md | Documents the Bug Agent among conductors and updates the command routing table accordingly. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| forward=() | ||
| while [[ $# -gt 0 ]]; do | ||
| case "$1" in | ||
| -h|--help) sed -n '2,40p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;; |
Comment on lines
+76
to
+94
| if [[ "${forward[0]}" == "health" ]]; then | ||
| echo "== bug agent: health-issue mode ==" | ||
| verdict="$(consult_vitals_verdict)" | ||
| echo " live vitals verdict: $verdict" | ||
| issues_json="$(mktemp)" | ||
| trap 'rm -f "$issues_json"' EXIT | ||
| if command -v gh >/dev/null 2>&1; then | ||
| echo " scanning filed PyAutoHeart issues: https://github.com/$HEART_ISSUES_REPO/issues" | ||
| gh issue list --repo "$HEART_ISSUES_REPO" --state open --limit 50 \ | ||
| --json number,title,labels,url > "$issues_json" 2>/dev/null \ | ||
| || echo "[]" > "$issues_json" | ||
| else | ||
| echo " (gh not available — skipping the filed-issue scan)" | ||
| echo "[]" > "$issues_json" | ||
| fi | ||
| echo | ||
| exec python3 "$HERE/_bug.py" --mind "$mind" --memory "$memory" \ | ||
| "${json_flag[@]}" health --verdict "$verdict" --heart-issues "$issues_json" | ||
| fi |
|
|
||
| # Optionally annotate a specific/selection decision with the vitals verdict | ||
| # (society-of-agents). This does not gate the decision — it informs it. | ||
| if [[ "$check_health" -eq 1 ]]; then |
Comment on lines
+282
to
+294
| prompts = [p for p in discover_bugs(mind) if p.name.lower() != "readme.md"] | ||
| in_flight = F._referenced_paths(mind, "active.md", "planned.md") | ||
| rows = [] | ||
| for path in prompts: | ||
| p = F.parse_prompt(path, mind) | ||
| level, score, factors = F.estimate_difficulty(p) | ||
| cls = classify(p, factors) | ||
| rows.append({ | ||
| "path": p["path"], "difficulty": level, "score": score, | ||
| "severity": cls["severity"], "type": cls["type"], | ||
| "in_flight": (p["path"] in in_flight) or ("bug/" + p["path"] in in_flight), | ||
| "factors": factors, | ||
| }) |
Comment on lines
+96
to
+104
| # scope — from the repo blast radius (single-file only when one repo + one @file). | ||
| n = factors["repos_affected"] | ||
| if n >= 3: | ||
| scope = "ecosystem" | ||
| elif n == 2: | ||
| scope = "multi-repo" | ||
| else: | ||
| scope = "single-repo" | ||
|
|
Comment on lines
+360
to
+361
| print(f"Filed PyAutoHeart issues ({len(issues)} open) — classify each real-bug / " | ||
| "flaky / config / expected, then route:") |
Comment on lines
+70
to
+73
| The bug can come from PyAutoHeart. `bug.sh health` gathers both signals and hands them | ||
| to `_bug.py`, which classifies each finding **real-bug / flaky / config / expected** and | ||
| decides whether the fix belongs in the affected repo, PyAutoHeart, PyAutoBuild or | ||
| PyAutoBrain: |
Comment on lines
+79
to
+84
| For each finding the agent decides **real-bug / flaky / config / expected** and where the | ||
| fix belongs (affected repo, PyAutoHeart, PyAutoBuild, PyAutoBrain). Real defects become | ||
| `PyAutoMind/bug/health_fixes/<name>.md` prompts and enter the normal workflow; flaky / | ||
| expected findings are left to the Health conductor's loop. Validation after patching is | ||
| always the vitals faculty (`pyauto-heart readiness` GREEN/YELLOW), never a check re-run | ||
| here. |
Comment on lines
+211
to
+212
| def health_validation(workflow: str, factors: dict) -> str: | ||
| """Which health signals must be GREEN (via the vitals faculty) before shipping.""" |
Comment on lines
+14
to
+16
| 2. **From PyAutoHeart** — run `bin/pyauto-brain bug health`: it reads the live vitals | ||
| verdict **and** scans the filed PyAutoHeart issues, routing real defects to | ||
| `PyAutoMind/bug/health_fixes/`. |
- bug.sh: route health / --check-health diagnostics to stderr so --json emits valid JSON on stdout; run (not exec) _bug.py in health mode so the EXIT trap cleans up the mktemp file; filter --help to comment lines only (no bash code). - _bug.py: add bug-path-aware in-flight scan (_feature._referenced_paths only matched feature/… paths, so bug prompts were never down-ranked); emit single-file scope when ≤1 repo references exactly one file; extend re_home_check to docs and research; add a per-Heart-issue category hint (health mode + --json) so the code matches the docs; align health_validation docstring with the GREEN/YELLOW policy. - docs: reword health-mode text in AGENTS.md / BUG_TAXONOMY.md / skills/bug/bug.md from "classifies + routes" to "hints a category; the reasoning layer confirms + routes"; fix the signal-discipline note (docstring is a kept specific marker). Refs #18 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Author
|
Thanks — addressed all 13 Copilot comments in Correctness
Spec/enum completeness
Doc/code honesty
All CLI modes re-verified (JSON purity, single-file scope, per-issue hints, temp cleanup); line-count guard passes. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the initial PyAutoBrain Bug Agent — a new conductor at
agents/conductors/bug/framed as the organism's immune system (organism-facingname: Immune Agent). It recognises a pathogen (a bug, regression, failing test or
PyAutoHeart finding), tells it from benign self, classifies it, recalls prior cases
from PyAutoMemory, decides where the fix belongs, and emits a
BugDecisiontheexisting
start_dev → ship_*workflow consumes. It reasons; it never edits source.It mirrors the Feature Agent, consults the read-only vitals faculty
(
--check-health) and never queries Heart directly, and encodes a "no autoimmunity"principle: user-facing workspace scripts are documentation, so a fix must prefer a
general library-source change over degrading a script (no injected test env-vars,
hard-coded paths,
os.environmutation, or silent guards).Closes #18.
What's new
agents/conductors/bug/AGENTS.md— Tier: conductor; immune-system opening; fourmodes; the "no autoimmunity" fundamental principle; the
BugDecisionschema; theHealth-conductor seam; the future
diagnosis-faculty seam; hard boundaries.agents/conductors/bug/BUG_TAXONOMY.md— classification (severity/scope/type/confidence), the fix-locus rules, the two health inputs, difficulty reuse.
agents/conductors/bug/_bug.py— reasoning core; imports_feature.py(no fork) and adds
classify/reproduction/fix_locus/health_mode;stdlib-only, offline, never writes.
agents/conductors/bug/bug.sh— entrypoint;--check-health+ ahealthsubcommand (live vitals verdict +
ghscan of filed PyAutoHeart issues).Command-surface promotion
/bugmoves from a work-type entry to a real conductor: registered inbin/pyauto-brain;skills/bug/bug.mdrewritten;/bugrelocated into thereal-conductors tier across
skills/COMMANDS.md,README.md,AGENTS.md.Design decisions (agreed before implementation)
vitalsfaculty, with a documented seamfor a future read-only
diagnosisfaculty (kept small, like Release-as-a-mode-of-Build).recommend); the Bug Agent is the deferred edit-in-fix arm it hands a real code failure.
(
gh issue list --repo PyAutoLabs/PyAutoHeart), routed toPyAutoMind/bug/health_fixes/.API Changes
None — PyAutoBrain is the Brain (reasoning layer), not a consumed PyPI library, so
there is no downstream workspace/API impact. This adds a new
pyauto-brain bugconductor and promotes the
/bugcommand; no existing agent or command behaviourchanges. See full details below.
Test Plan
No repo unit-test suite exists for the Brain agents; validation is the CLI-mode
contract (mirroring how the Feature Agent is exercised). All verified on this branch:
pyauto-brain bug bug/autoarray/rect_adapt.md— specific: classifieswrong-result, fix-locus library source.pyauto-brain bug— selection ranks severity-first (critical bugs surface first).pyauto-brain bug select --difficulty easy/--impact— difficulty-constrained.pyauto-brain bug health— consults vitals (YELLOW) and scans filed PyAutoHeartissues (Resolve the release seam: one gate implementation #27/Add /health full mode (release-run dashboard) #19/docs(health): record day-to-day operating defaults for pyauto-brain health #10/address Copilot review from #6 #7) →
bug/health_fixes/.pyauto-brain bug --json …— emits aBugDecision(JSON-consistent withFeatureDecision).bug/prompt that is really a feature → re-homes tofeature/.bin/check_skill_line_counts.shpasses;_bug.pycompiles; no__pycache__/binary leak (gitignored).Full details (for automation & release notes)
Added
pyauto-brain bugconductor with modes:specific·selection·difficulty-constrained(--difficulty/--model/--budget/--ambitious/--impact) ·health. Flags:--check-health,--json. Env:$PYAUTO_HEART_REPOoverrides thePyAutoHeart issues repo.
BugDecisionfields:classification{severity,scope,type,confidence},likely_owner,reproduction,memory_context,fix_locus{locus,note},fix_strategy,recommended_workflow,rehome_suggestion,difficulty(+score/factors),health_validation,risks,next_action.Changed (command surface)
/bugpromoted work-type-entry → real conductor inbin/pyauto-brain,skills/bug/bug.md,skills/COMMANDS.md,README.md,AGENTS.md.Notes
health-one-door(Make /health the single health door (3 modes) #17/Add /health full mode (release-run dashboard) #19) merged during development; this branch wasrebased onto the updated
main— disjoint files, no conflicts.PyAutoMind/bug/pyautobrain/feature_agent_infra_target_resolution.md):the Feature Agent can't resolve the
pyautobraininfra target, so it misfiredresearch-firston this prompt (overridden by hand here).🤖 Generated with Claude Code